home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 22 / Cream of the Crop 22.iso / os2 / wptool19.zip / wptools.txt < prev   
Text File  |  1996-09-30  |  9KB  |  268 lines
  1.                           === DISCLAIMER ===
  2.  
  3.  
  4. I allow you to use and distribute WPTOOLS.DLL freely under the condition
  5. that I am in no way responsible for any damage or loss you may suffer.
  6.  
  7. Henk Kelder
  8.  
  9. hkelder@inetgate.capvolmac.nl
  10. 100321,3650@compuserve.com
  11.  
  12.  
  13. What is WPTOOLS.DLL:
  14.  
  15. WPTOOLS.DLL is a Dynamic Link Library that contains code to query the
  16. settings for workplace shell objects. This DLL is used by WPSBKP.EXE but
  17. can also be used from within a REXX program.
  18.  
  19.  
  20. The following REXX functions are available:
  21.  
  22.  
  23.  
  24. Function: WPToolsLoadFuncs
  25. Purpose : Make the functions in WPTOOLS.DLL available to REXX.
  26.  
  27. Usage:
  28.  
  29. /*  First declare WPToolsLoadFuncs itself to REXX */
  30. call RxFuncAdd 'WPToolsLoadFuncs', 'WPTOOLS', 'WPToolsLoadFuncs'
  31. /*  Call WPToolsLoadFuncs itself. */
  32. call WPToolsLoadFuncs
  33.  
  34.  
  35.  
  36. Function: WPToolsQueryObject
  37. Purpose : Query objects
  38.  
  39. Usage  :  rc=WPToolsQueryObject(object, [Class], [Title], [Setup], [Location])
  40.  
  41. Where:
  42.         object = A fully qualified path name to a file or directory, or
  43.                  An OBJECTID string (e.g. <WP_DESKTOP>), or
  44.                  A string starting with a '#' and being followed
  45.                  by a hexadecimal object handle (See WPToolsFolderContent)
  46.  
  47.         Class  = The name of a REXX variable, enclosed in quotes,
  48.                  that will be created by WPTOOLS and will contain the
  49.                  class name of the object. This argument is optional.
  50.  
  51.         Title  = The name of a REXX variable, enclosed in quotes,
  52.                  that will be created by WPTOOLS and will contain the
  53.                  title of the object. This argument is optional.
  54.  
  55.         Setup  = The name of a REXX variable, enclosed in quotes,
  56.                  that will be created by WPTOOLS and will contain the
  57.                  setup string of the object. This argument is optional.
  58.  
  59.         Location = The name of a REXX variable, enclosed in quotes,
  60.                  that will be created by WPTOOLS and will contain the
  61.                  location of the object. This argument is optional.
  62.  
  63. Returns: 1 on success and 0 when a error occurred.
  64.  
  65. Please note that only the object argument is mandatory. All other arguments
  66. only need to be present when the result is needed. Should you not need one
  67. argument, but need a argument that is after the not needed one, make sure
  68. you enter all comma's. (e.g.: rc = WPToolsQueryObject(object,,,"SetupString")
  69.  
  70. See Appendix I and II for information about objects and the setup values
  71. this call returns.
  72.  
  73.  
  74. Example:
  75.  
  76. /* REXX must start with a comment line */
  77.  
  78. call RxFuncAdd 'WPToolsLoadFuncs', 'WPTOOLS', 'WPToolsLoadFuncs'
  79. call WPToolsLoadFuncs
  80.  
  81. iRetco = WPToolsQueryObject("<WP_DESKTOP>", "szClass", "szTitle", "szSetupString", "szLocation")
  82. if Iretco Then do
  83.      say 'Class name :' szclass
  84.      say 'Title      :' sztitle
  85.      say 'Location   :' szlocation
  86.      say 'Setupstring:' szsetupstring
  87.   end
  88. else
  89.   say 'Unable to return object settings for <WP_DESKTOP>'
  90.  
  91. End of Example
  92.  
  93.  
  94. Function: WPToolsFolderContent
  95. Purpose : Query abstract (non-disk) objects in a specific folder
  96.  
  97. Usage   : rc=WPToolsFolderContent(folder, stem)
  98.  
  99. Where   :
  100.  
  101.         folder = A fully qualified path name to a directory, or
  102.                  an OBJECTID string for a folder (e.g. <WP_DESKTOP>
  103.  
  104.         stem   = The name of a REXX stem variable that, on successful
  105.                  return, will contain all abstract objects present
  106.                  in a specific folder. Each returned entry will either
  107.                  be an OBJECTID (when an OBJECTID has been set for
  108.                  the returned object) or a string starting with a '#' and
  109.                  followed by the hexadecimal object handle.
  110.  
  111.  
  112. Returns: 1 on success and 0 when a error occurred.
  113.  
  114. Example:
  115.  
  116. /* REXX must start with a comment line */
  117.  
  118. call RxFuncAdd 'WPToolsLoadFuncs', 'WPTOOLS', 'WPToolsLoadFuncs'
  119. call WPToolsLoadFuncs
  120.  
  121. Iretco = WPToolsFolderContent("<WP_DESKTOP>", "list.")
  122. if Iretco = 0 Then Do
  123.    exit
  124. End
  125.  
  126. say 'Abstract objects on <WP_DESKTOP>:'
  127. do iObject = 1 to list.0
  128.   Iretco=WPToolsQueryObject(list.Iobject, "szclass", "sztitle", "szsetupstring", "szlocation")
  129.   if Iretco Then do
  130.      say '"'szClass'", "'szTitle'", "'szSetupString'", "'szLocation'"'
  131.   end
  132. end
  133.  
  134. End of Example
  135.  
  136. Function: WPToolsVersion
  137. Purpose : Query version of WPTOOLS.DLL
  138.  
  139. Usage  :  version=WPToolsVersion()
  140.  
  141. Example:
  142.  
  143. /* REXX must start with a comment line */
  144.  
  145. call RxFuncAdd 'WPToolsLoadFuncs', 'WPTOOLS', 'WPToolsLoadFuncs'
  146. call WPToolsLoadFuncs
  147.  
  148. Version = WPToolsVersion()
  149. say 'WPTOOLS.DLL is of version' version
  150.  
  151. End of Example
  152.  
  153. APPENDIX I - The workplace shell class tree
  154.  
  155.       WPObject                       Base object class
  156.         ├── WPAbstract               Base abstract object class
  157.         │     ├── WPClock
  158.         │     ├── WPCountry
  159.         │     ├── WPDisk
  160.         │     ├── WPLaunchPad
  161.         │     ├── WPKeyboard
  162.         │     ├── WPMouse
  163.         │     ├── WPPalette
  164.         │     │     ├── WPColorPalette
  165.         │     │     ├── WPFontPalette
  166.         │     │     └── WPSchemePalette
  167.         │     ├── WPPower
  168.         │     ├── WPPrinter
  169.         │     ├── WPProgram
  170.         │     ├── WPShadow
  171.         │     │      └── WPNetLink
  172.         │     ├── WPShredder
  173.         │     ├── WPSound
  174.         │     ├── WPSpecialNeeds
  175.         │     ├── WPSpool
  176.         │     └── WPSystem
  177.         ├── WPFileSystem
  178.         │     ├── WPDataFile
  179.         │     │      ├── WPBitmap
  180.         │     │      ├── WPIcon
  181.         │     │      ├── WPMet
  182.         │     │      ├── WPPif
  183.         │     │      ├── WPPointer
  184.         │     │      └── WPProgramFile
  185.         │     │             └── WPCommandFile
  186.         │     ├── WPFolder
  187.         │     │      ├── WPDesktop
  188.         │     │      ├── WPDrives
  189.         │     │      ├── WPMinWinViewer
  190.         │     │      ├── WPNetgrp
  191.         │     │      ├── WPNetwork
  192.         │     │      ├── WPRootFolder
  193.         │     │      ├── WPServer
  194.         │     │      ├── WPSharedDir
  195.         │     │      ├── WPStartup
  196.         │     │      └── WPTemplates
  197.         │     └── WPWinConfig
  198.         └── WPTransient
  199.               ├── WPJob
  200.               ├── WPPort
  201.               ├── WPPdr
  202.               └── WPQdr
  203.  
  204.  
  205. APPENDIX II
  206.  
  207. WPToolsQueryObject has code to support (almost) all object classes for
  208. which object setup strings are defined, being:
  209.  
  210. Class             Setup strings returned
  211. -----             ----------------------
  212.  
  213. WPObject          CCVIEW, DEFAULTVIEW, HELPPANEL, HIDEBUTTON, MINWIN, NOCOPY,
  214.                   NODELETE, NODRAG, NODROP, NOLINK, NOMOVE, NOPRINT, NORENAME,
  215.                   NOSETTINGS, NOSHADOW, NOTVISIBLE, OBJECTID, TITLE
  216. WPAbstract        TEMPLATE
  217. WPProgram         ASSOCFILTER, ASSOCTYPE, EXENAME, MAXIMIZED, MINIMIZED,
  218.                   NOAUTOCLOSE, PARAMETERS, PROGTYPE, SET, STARTUPDIR
  219. WPShadow          SHADOWID
  220. WPRPrinter        NETID (1)
  221. WPPrint           APPDEFAULT, JOBDIALOGBEFOREPRINT, OUTPUTTOFILE, PORTNAME,
  222.                   PRINTDRIVER, PRINTERSPECIFICFORMAT, PRINTWHILESPOOLING,
  223.                   QSTARTTIME, QSTOPTIME, QUEUENAME, QUEUEDRIVER, SEPARATORFILE
  224. WPServer          NETID (2)
  225. WPNetgrp          NETID (2)
  226. WPDisk            DRIVENUM
  227. WPFontPalette     FONTS, XCELLCOUNT, YCELLCOUNT, XCELLWIDTH, XCELLHEIGHT,
  228.                   XCELLGAP, YCELLGAP
  229. WPColorPalette    COLORS, XCELLCOUNT, YCELLCOUNT, XCELLWIDTH, XCELLHEIGHT,
  230.                   XCELLGAP, YCELLGAP
  231. WPFileSystem      MENU (3)
  232. WPProgramFile     ASSOCFILTER, ASSOCTYPE, EXENAME, MAXIMIZED, MINIMIZED,
  233.                   NOAUTOCLOSE, PARAMETERS, PROGTYPE, SET, STARTUPDIR
  234. WPFolder          ALWAYSSORT, BACKGROUND, DETAILSCLASS, DETAILSFONTS,
  235.                   ICONFONT, TREEFONT, ICONNFILE, ICONVIEW, SORTCLASS,
  236.                   TREEVIEW, DETAILSVIEW, WORKAREA,
  237. WPLaunchPad       All documented setup strings.
  238.  
  239. (1) Along with all settings for WPPrint.
  240. (2) These settings cannot be used to recreate the object.
  241. (3) MENU doesn't work when applying.
  242.  
  243. For each object, WPToolsQueryObject returns setup string values not only for the object
  244. itself (when supported) but also for all parent classes. When, for example,
  245. one uses WPToolsQueryObject against the Desktop (class WPDesktop) setup strings
  246. will be returned from the classes WPFolder, WPFileSystem and WPObject.
  247.  
  248. I did not build any support for WPSchemePalette because the setup string
  249. for this class do not support settings the colors on an individual basis but
  250. instead one should specify a color scheme name that is already present
  251. in the INI files.
  252.  
  253.  
  254. HISTORY:
  255.  
  256. Version 1.00 - Initial release
  257.  
  258. Version 1.01 - Added support for the Launchpad.
  259.                Added a new REXX API call: WPToolsVersion
  260.  
  261. Version 1.02/1.19 - Not released
  262.  
  263. Version 1.20 - Increased several internal buffers to accommodate OS/2
  264.                Warp Version 4 (Merlin) GAMMA.
  265.  
  266. Version 1.21 - Changed the return code from WPToolsFolderContent for '0' to '1'
  267.                when a folder does not contain any abstract objects.
  268.